---
title: Webhook 触发器
---

## 简介

<Info>
    触发器仅适用于 Workflow 应用。
</Info>

Webhook 允许一个系统自动向另一个系统发送实时数据。当某个特定事件发生时，源系统将事件详情打包进一个 HTTP 请求，并发送至目标系统的指定 URL。

遵循相同的机制，Webhook 触发器能够让 Workflow 在外部事件发生时自动运行：

1. 在 Workflow 中添加 Webhook 触发器后，系统将自动生成一个 webhook URL 作为监听外部 HTTP 请求的专用端点。

    <Info>
        对于自托管部署，可通过 `TRIGGER_URL` 环境变量更改此 URL 的基础前缀。需确保其指向外部系统可访问的公共域名或 IP 地址。
    </Info>

2. 你使用此 URL 在外部系统中创建一个 webhook，订阅期望关注的事件。然后，在 Dify 中配置 Webhook 触发器，定义其如何处理接收到的请求并提取请求中的事件数据。

    <Note>
        在测试场景中，请始终使用测试专用的 webhook URL，以分离测试与生产数据。
        <img src="/images/test_webhook_url.png" alt="Test Webhook URL" width="563" />
    </Note>

3. 当订阅的事件发生时，外部系统会将包含事件数据的 HTTP 请求发送到先前提供的 webhook URL。一旦请求被成功接收和处理，你的 Workflow 会被触发，而提取到的事件数据也将成为下游节点可引用的变量。

<Tip>
    若目标外部系统有可用的触发器插件，推荐使用 [插件触发器](/zh-hans/guides/workflow/node/plugin-trigger)。
</Tip>

## 添加 Webhook 触发器

在 Workflow 画布上，单击右键并选择 **添加节点** > **开始** > **Webhook 触发器**。

<Tip>
    一个 Workflow 可同时拥有多个并行的 Webhook 触发器。当并行的分支连续包含相同节点时，可在相同部分之前添加 [变量聚合节点](/zh-hans/guides/workflow/node/variable-aggregator) 以合并分支，而无需在每个分支中分别重复添加相同的节点。
</Tip>

## 配置 Webhook 触发器

你可以定义 Webhook 触发器如何处理接收到的 HTTP 请求，包括：

- Webhook URL 接受的 HTTP 方法

- 请求的内容类型

- 需要从请求中提取的事件数据

- 当 Workflow 成功触发时，返回至外部系统的响应

<Note>
    如需测试未发布的 Webhook 触发器，必须先点击 **运行此步骤** 或测试运行整个 Workflow，使触发器进入监听状态。否则，将无法接收到外部请求。
</Note>

### HTTP 方法

为了确保传入的请求被成功接收，需指定 webhook URL 接受的 HTTP 方法。

在此处选择的方法，必须与外部系统发送请求时使用的方法一致。否则，请求将被拒绝。

<Tip>
    通常，你可以在外部系统的 webhook 文档或设置界面中找到该信息。
</Tip>

### 内容类型

为了确保请求体被正确解析且特定数据被成功提取，需指定外部请求的预期内容类型。

在此处选择的内容类型，必须与外部系统发送的请求的内容类型一致。否则，请求将被拒绝。

### 查询参数、请求头参数和请求体参数

你可以从传入请求的查询参数、请求头和请求体中提取特定参数。**每个提取出的参数都将成为一个输出变量，可供下游节点引用。**

许多外部系统支持查看已发出请求的日志，可在其中浏览请求包含的所有数据，并确定需要提取的参数。

或者，你也可以让外部系统向 Webhook 触发器发送测试请求，然后在触发器的 **上次运行** 日志中查看接收到的请求数据：

1. 使用 Dify 提供的测试专用 webhook URL 在外部系统中创建一个 webhook。

2. 在触发器中设置正确的 HTTP 方法和内容类型。

3. 点击触发器的 **运行此步骤** 图标，使其开始监听外部请求。

4. 在外部系统中手动触发已订阅的事件，使其向 Dify 的 webhook URL 发送 HTTP 请求。

5. 点开触发器的 **上次运行** 日志，在 **输入** 中查看接收到的请求数据。

<Note>
    在触发器内定义的变量名，必须与请求中对应参数的键名一致。
</Note>

<Tabs>
    <Tab title="查询参数">

        - 外部系统在发送请求时添加到 webhook URL（`?` 之后）的键值对参数，每对参数之间用 `&` 分隔。

        - 通常是关于事件的简单、非敏感的标识符或过滤数据。 

        - 示例：从 URL `{webhook url}?userID=u-456&source=email` 中，可提取 `userID`（`u-456`）或 `source`（`email`）。
    </Tab>
    <Tab title="请求头参数">

        - 包含在请求头中的请求元数据。

        - 处理请求所需的技术信息，例如身份验证令牌或请求体的内容类型。

        - 示例：从类似 `Authorization: Bearer sk-abc...` 和 `Content-Type: application/json` 的请求头中，可提取授权信息（`Bearer sk-abc...`）或内容类型（`application/json`）。
    </Tab>
    <Tab title="请求体参数">

        - 发送核心事件数据的主要有效负载，例如客户资料、订单详情或 Slack 消息的具体内容。

        - 示例：从以下请求体中，可提取 `customerName`（`Alex`）、`items` 列表或 `isPriority` 状态（`true`）。

        ```JSON
        "customerName": "Alex",
        "items": 
        [
                { "sku": "A42", "quantity": 2 },
                { "sku": "B12", "quantity": 1 }
        ],
        "isPriority": true
        ```

        <Info>
            可从请求体中提取的参数数据类型，取决于请求的内容类型。

                | 内容类型 | `String` | `Number` | `Boolean` | `Object` | `File` | `Array[String]` | `Array[Number]` | `Array[Boolean]` | `Array[Object]` | `Array[File]` |
                |:--------------|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|
                | application/json | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
                | application/x-www-form-urlencoded | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ |
                | multipart/form-data | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
                | text/plain | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
        </Info>
    </Tab>
</Tabs>

**参数设置**

对于要提取的每个参数，可进行以下设置：

- **变量名**：请求中对应参数的键名（例如，`userID=u-456` 中的 `userID`）。

    <Note>
        对于请求头参数，变量名中的任何连字符（`-`）将在输出变量中自动转换为下划线（`_`）。
    </Note>

- **类型**: 预期的数据格式。仅适用于查询参数和请求体参数，因为请求头参数的格式始终被视为字符串。

- **必填**: 该参数是否对你的 Workflow 是必需的。若传入请求中缺少任何必填参数，Workflow 将不会被触发。

### 响应

当 Workflow 被外部请求成功触发时，Dify 会向外部系统返回一个默认的 `200 OK` 响应。

若外部系统对成功响应的格式有特定要求，你可以自定义其状态码和响应体。默认响应将被覆盖。

- **状态码**: 支持 [200, 399] 范围内的任何状态码。

- **响应体**: 支持 JSON 或纯文本。

<Note>
    在返回的响应体中，非 JSON 内容将自动转换为 JSON 格式。
    
    例如，`OK` 将被转换为 `"message": "OK"`。
</Note>

<Info>
    以下错误响应由系统定义，无法自定义。错误详情可在响应体中查看。 
        - 400 Bad Request
        - 404 Not Found
        - 413 Payload Too Large
        - 500 Internal Server Error
</Info>

## 测试 Webhook 触发器

如需测试未发布的 Webhook 触发器，必须先点击 **运行此步骤** 或测试运行整个 Workflow，使触发器进入监听状态。否则，将无法接收到外部请求。

{/*
Contributing Section
DO NOT edit this section!
It will be automatically generated by the script.
*/}

---

[编辑此页面](https://github.com/langgenius/dify-docs/edit/main/zh-hans/guides/workflow/node/webhook-trigger.mdx) | [提交问题](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)

